<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.3" />
<title>CCNx Face Management and Registration Protocol</title>
<style type="text/css">
/* Sans-serif font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
div#toctitle,
span#author, span#revnumber, span#revdate, span#revremark,
div#footer {
  font-family: Arial,Helvetica,sans-serif;
}

/* Serif font. */
div.sectionbody {
  font-family: Georgia,"Times New Roman",Times,serif;
}

/* Monospace font. */
tt {
  font-size: inherit;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  font-size: inherit;
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
}

div#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes();}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>CCNx Face Management and Registration Protocol</h1>
</div>
<div id="content">
<div class="sect1">
<h2 id="_face_management_protocol">Face Management Protocol</h2>
<div class="sectionbody">
<div class="paragraph"><p>The Face Management Protocol provides a method for an entity such as ccndc to control
the faces maintained by ccnd, which are subsequently used in the Registration Protocol.</p></div>
<div class="paragraph"><p>The FMP supports "newface", "destroyface", and "queryface" operations.</p></div>
<div class="paragraph"><p>A request operation is represented as a CCNx Interest with
a CCNx ContentObject encoding the majority of the request parameters embedded
as a component of the Interest name.
A response is represented as a ContentObject for which the name matches the Interest,
and the content encodes any necessary response data.</p></div>
<div class="paragraph"><p>For the Face Management Protocol, the CCNx ContentObject encoding the request and reply
is the FaceInstance.</p></div>
<div class="paragraph"><p>To create a new face ccndc signs a content object NFBLOB whose Content is a
ccnb-encoded FaceInstance containing</p></div>
<div class="ulist"><ul>
<li>
<p>
Action "newface"
</p>
</li>
<li>
<p>
other fields necessary to set up a socket (at least IPProto, Host, and Port).
</p>
</li>
</ul></div>
<div class="paragraph"><p>ccndc then expresses an interest in /ccnx/CCNDID/newface/NFBLOB</p></div>
<div class="ulist"><ul>
<li>
<p>
CCNDID is the pubid of the local ccnd
</p>
</li>
<li>
<p>
NFBLOB is the signed content object
</p>
</li>
</ul></div>
<div class="paragraph"><p>The verb, "newface" occurs redundantly in both the interest prefix and in the NFBLOB.
Its presence in the prefix is for dispatching the request.
It is also in the NFBLOB, so that it is signed.</p></div>
<div class="paragraph"><p>ccnd creates the new face and answers with a FaceInstance containing
at least the PublisherPublicKeyDigest and FaceID.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_faceinstance">FaceInstance</h2>
<div class="sectionbody">
<div class="paragraph"><p>See ccnx.xsd/ccnx.dtd</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>FaceInstance ::= Action?
                 PublisherPublicKeyDigest?
                 FaceID?
                 IPProto?
                 Host?
                 Port?
                 MulticastInterface?
                 MulticastTTL?
                 FreshnessSeconds?

Action           ::= ("newface" | "destroyface" | "queryface")
PublisherPublicKeyDigest ::= SHA-256 digest
FaceID           ::= nonNegativeInteger
IPProto          ::= nonNegativeInteger [IANA protocol number; 6=TCP, 17=UDP]
Host             ::= textual representation of numeric IPv4 or IPv6 address
Port             ::= nonNegativeInteger [1..65535]
MulticastInterface ::= textual representation of numeric IPv4 or IPv6 address
MulticastTTL     ::= nonNegativeInteger [1..255]
FreshnessSeconds ::= nonNegativeInteger</tt></pre>
</div></div>
<div class="sect2">
<h3 id="_action">Action</h3>
<div class="paragraph"><p>When FaceInstance is used as a request, the Action must be specified.
It will not be present in a response.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
<tt>newface</tt> - If a face matching the parameters does not already exist,
   an attempt is made to create it.
   Then if the face exists (whether new or old)
   the full description is returned as a FaceInstance.
</p>
</li>
<li>
<p>
<tt>destroyface</tt> - at least the FaceID must be present.
   If permitted, the face is destroyed.
</p>
</li>
<li>
<p>
<tt>queryface</tt> - specification TBD
</p>
</li>
</ol></div>
</div>
<div class="sect2">
<h3 id="_publisherpublickeydigest">PublisherPublicKeyDigest</h3>
<div class="paragraph"><p>Identifies the ccnd that the information is relevant for.
PublisherPublicKeyDigest is not necessary for self-registration, but
indicates the ccnd to which the request is directed, if present.
PublisherPublicKeyDigest is always present in a response.</p></div>
</div>
<div class="sect2">
<h3 id="_faceid">FaceID</h3>
<div class="paragraph"><p>FaceID is not present in a <tt>newface</tt> request, but must be specified in
a <tt>destroyface</tt> or <tt>queryface</tt> request.
FaceID is always present in a response.</p></div>
</div>
<div class="sect2">
<h3 id="_host">Host</h3>
<div class="paragraph"><p>Identifies the IPv4 or IPv6 numeric address of the remote ccnd for this
FaceInstance.</p></div>
</div>
<div class="sect2">
<h3 id="_port">Port</h3>
<div class="paragraph"><p>Port identifies the port on the remote ccnd, or the port for the multicast group.</p></div>
</div>
<div class="sect2">
<h3 id="_multicastinterface">MulticastInterface</h3>
<div class="paragraph"><p>If the Host is a multicast address, and there are multiple
interfaces present, MulticastInterface will identify the unicast
numeric address of the interface to which the multicast address will be
attached.</p></div>
</div>
<div class="sect2">
<h3 id="_multicastttl">MulticastTTL</h3>
<div class="paragraph"><p>Specifies the TTL to be used for multicast operations.  The default value is 1.</p></div>
</div>
<div class="sect2">
<h3 id="_freshnessseconds">FreshnessSeconds</h3>
<div class="paragraph"><p>FreshnessSeconds is optional in a request, but is treated as a hint by ccnd.
In a response, FreshnessSeconds specifies the remaining lifetime of the
face.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_prefix_registration_protocol">Prefix Registration Protocol</h2>
<div class="sectionbody">
<div class="paragraph"><p>The prefix registration protocol uses the ForwardingEntry element type
to represent both requests and responses.</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>ForwardingEntry ::= Action?
                    Name?
                    PublisherPublicKeyDigest?
                    FaceID?
                   ForwardingFlags?
                   FreshnessSeconds?

Action           ::= ("prefixreg" | "selfreg" | "unreg")
Name             ::= the name prefix to be registered
PublisherPublicKeyDigest ::= SHA-256 digest of the ccnd's public key (CCNDID)
FaceID           ::= nonNegativeInteger
ForwardingFlags  ::= nonNegativeInteger
FreshnessSeconds ::= nonNegativeInteger</tt></pre>
</div></div>
<div class="sect2">
<h3 id="_action_2">Action</h3>
<div class="paragraph"><p>When ForwardingEntry is used as a request, the Action must be specified.
It will not be present in a response.</p></div>
<div class="ulist"><ul>
<li>
<p>
<tt>prefixreg</tt> - Register (or re-register) the prefix on the specified face.
</p>
</li>
<li>
<p>
<tt>selfreg</tt> - Register (or re-register) the prefix on the current face; the
  FaceID need not be present in the request, but if present it must match
  the current face.
</p>
</li>
<li>
<p>
<tt>unreg</tt> - Remove the prefix registration for the specified face.
</p>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_publisherpublickeydigest_2">PublisherPublicKeyDigest</h3>
<div class="paragraph"><p>Identifies the ccnd that the information is relevant for.
It is optional in a request (the name in the requesting interest has
already addressed the appropriate node).
PublisherPublicKeyDigest is always present in a response.</p></div>
</div>
<div class="sect2">
<h3 id="_faceid_2">FaceID</h3>
<div class="paragraph"><p>FaceID is required in <tt>prefixreg</tt> and <tt>unreg</tt> requests.
FaceID is always present in a response.</p></div>
</div>
<div class="sect2">
<h3 id="_name">Name</h3>
<div class="paragraph"><p>This is the name prefix that is to acted on.</p></div>
</div>
<div class="sect2">
<h3 id="_forwardingflags">ForwardingFlags</h3>
<div class="paragraph"><p>This integer holds the inclusive OR of the following bit fields:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>CCN_FORW_ACTIVE         1
CCN_FORW_CHILD_INHERIT  2
CCN_FORW_ADVERTISE      4
CCN_FORW_LAST           8
CCN_FORW_CAPTURE       16
CCN_FORW_LOCAL         32
CCN_FORW_TAP           64
CCN_FORW_CAPTURE_OK   128</tt></pre>
</div></div>
<div class="paragraph"><p>The <tt>CCN_FORW_ACTIVE</tt> bit indicates that the entry is active;
interests will not be sent for inactive entries (but see note below).</p></div>
<div class="paragraph"><p><tt>CCN_FORW_CHILD_INHERIT</tt> says that this entry may be used even if there is a
longer match available.
In the absence of this bit, the presence of a longer matching prefix that
has an active entry will prevent this entry from being used.</p></div>
<div class="paragraph"><p><tt>CCN_FORW_ADVERTISE</tt> says that the prefix may be advertised to other nodes.</p></div>
<div class="paragraph"><p><tt>CCN_FORW_LAST</tt> indicates that this entry should be used last, if nothing else
worked.
This is intended to be used by ccndc and similar programs to monitor
unanswered interests.
The presence of this flag on any entry causes the associated face to be considered non-local, as far as interest forwarding is concerned.
Thus it will not receive interests with Scope=1, nor will it receive interests in namespaces that are marked local.
However, the ability of the face to change prefix registrations is not affected.</p></div>
<div class="paragraph"><p><tt>CCN_FORW_CAPTURE</tt> says that no shorter prefix may be used, overriding
child-inherit bits that would otherwise make the shorter entries usable.
For a child-inherit bit to be overridden, the CCN_FORW_CAPTURE_OK must be set
in the same forwarding entry that has CCN_FORW_CHILD_INHERIT set.
Note that this means that using CCN_FORW_CAPTURE will have no effect if the
CCN_FORW_CAPTURE_OK flag is not used.</p></div>
<div class="paragraph"><p><tt>CCN_FORW_LOCAL</tt> restricts the namespace to use by applications on the local
machine.</p></div>
<div class="paragraph"><p><tt>CCN_FORW_TAP</tt> causes the entry to be used right away.  This is intended for debugging and monitoring purposes.  It is likely that there will be no response as a result, so no intentional delay is added before any further forwarding of this interest.</p></div>
<div class="paragraph"><p>&#8216;CCN_FORW_CAPTURE_OK&#8217; used in conjunction with CCN_FORW_CHILD_INHERIT allows a
CCN_FORW_CAPTURE flag on a longer prefix to override the effect of the child-inherit bit.</p></div>
<div class="paragraph"><p>The flags <tt>CCN_FORW_ADVERTISE</tt>, <tt>CCN_FORW_CAPTURE</tt> and <tt>CCN_FORW_LOCAL</tt> affect
the prefix as a whole, rather than the individual registrations.
Their effects take place whether or not the <tt>CCN_FORW_ACTIVE</tt> bit is set.</p></div>
</div>
<div class="sect2">
<h3 id="_freshnessseconds_2">FreshnessSeconds</h3>
<div class="paragraph"><p>FreshnessSeconds is optional in a request, but is treated as a hint by ccnd.
In a response, FreshnessSeconds specifies the remaining lifetime of the
registration.</p></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2011-05-12 00:55:23 PDT
</div>
</div>
</body>
</html>
